Skip to content

Add swap-in wallet and splice-in via Electrum backend#1

Open
matthiasdebernardini wants to merge 1 commit intomasterfrom
feat/swap-in-electrum
Open

Add swap-in wallet and splice-in via Electrum backend#1
matthiasdebernardini wants to merge 1 commit intomasterfrom
feat/swap-in-electrum

Conversation

@matthiasdebernardini
Copy link
Copy Markdown
Owner

@matthiasdebernardini matthiasdebernardini commented Mar 9, 2026

Summary

  • Switches blockchain backend from MempoolSpaceClient to ElectrumClient, enabling peer.swapInWallet (gated behind IElectrumClient)
  • Adds --electrum-server CLI option with per-chain defaults (ACINQ's Electrum servers), deprecates --mempool-space-url
  • Adds 3 new API endpoints: GET /getswapinaddress, GET /swapinwalletbalance, POST /splicein (full-access)
  • Adds corresponding CLI commands: getswapinaddress, swapinwalletbalance, splicein
  • Includes an interactive E2E test script (tests/test_swap_in_e2e.sh)

Ports the core functionality from ACINQ/phoenixd#69 to current master, following the same pattern Phoenix mobile uses.

Status

⚠️ UNTESTED — Compiles cleanly against lightning-kmp 1.11.4 but has not been tested against a running phoenixd instance or on testnet. Needs:

  • Build with lightning-kmp 1.11.5-SNAPSHOT (requires local build of lightning-kmp)
  • Run ./phoenixd --chain testnet and verify Electrum + peer connections
  • phoenix-cli getswapinaddress returns valid testnet address
  • Send testnet coins and verify balance updates
  • Splice-in succeeds and channel balance increases
  • Verify existing functionality (payments, splice-out, etc.) still works after backend switch

Test plan

  • Compile with lightning-kmp 1.11.5-SNAPSHOT via mavenLocal
  • Start phoenixd on testnet, confirm Electrum connection log message
  • Run tests/test_swap_in_e2e.sh through the full swap-in → splice-in → splice-out cycle
  • Regression test existing API endpoints (getinfo, getbalance, createinvoice, payinvoice, sendtoaddress)

🤖 Generated with Claude Code

@matthiasdebernardini @claude
Add swap-in wallet, balance, and splice-in endpoints via Electrum bac…
069f45a 
…kend

Port swap-in functionality from PR ACINQ#69 to current master by switching the
blockchain backend from MempoolSpaceClient to ElectrumClient. This enables
peer.swapInWallet (which requires IElectrumClient) and adds three new API
endpoints: getswapinaddress, swapinwalletbalance, and splicein.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@matthiasdebernardini
Copy link
Copy Markdown
Owner Author

matthiasdebernardini commented Mar 10, 2026

Mainnet E2E Test Report

Setup

  • Branch: feat/swap-in-electrum (commit 069f45a)
  • lightning-kmp: Built 1.11.5-SNAPSHOT from source (published to local Maven)
  • Runtime: JVM distribution on macOS, JDK 21
  • Electrum server: electrum.acinq.co:50002 (mainnet)
  • HTTP port: 9741 (9740 was occupied by Docker)

What Worked

Endpoint Status Notes
GET /getswapinaddress ✅ Returns taproot address + derivation index, auto-rotates after use
GET /swapinwalletbalance ✅ Correctly tracks total and unconfirmed balances
POST /splicein ✅ (untested manually) Auto splice-in flow triggered correctly
POST /sendtoaddress (splice-out) ✅ Successfully sent 19,000 sat on-chain
GET /getbalance ✅ Existing endpoint unaffected
GET /getinfo ✅ Shows channel state correctly
Electrum connection ✅ Connected to electrum.acinq.co:50002, push-based address monitoring
Swap-in address generation ✅ Derived addresses with look-ahead, auto-rotation on use
UTXO detection ✅ Near-instant via Electrum subscription notifications
Confirmation tracking ✅ Correct progression: unconfirmed → weaklyConfirmed → deeplyConfirmed
Auto channel request ✅ Triggered at deeplyConfirmed threshold with correct UTXO selection

Deposits Made (mainnet, real sats)

# Amount Address Index
1 3,333 sat bc1pam8adk0zjpn5ehu3naclr0ru3un55tv8pts8q3lxyugrdh3z4pgq2ljhyq 0
2 13,000 sat bc1pd03wzcvlgkm2cky6xyz27jt8zkspncgmr2nt3f5dp9u8dfcra3wszf503m 1
3 6,000 sat bc1pm8uwc079fs3f5r0r65kaf4re49h78fg66yy9h98hl9fyc9sac8nqtcvl3v 2
Total 22,333 sat

Timeline

Time (UTC) Block Event
01:07 940050 phoenixd started on mainnet, Electrum + peer connected
01:15 940050 Deposit 1 detected (3,333 sat unconfirmed)
01:28 940050 Deposit 2 detected (13,000 sat unconfirmed)
01:37 940051 Both deposits confirmed (weaklyConfirmed=16,333 sat)
02:20 940053 All deeplyConfirmed. Auto channel request: fees=21,619 > available=16,333 — insufficient funds
~02:36 940054 Deposit 3 sent (6,000 sat), detected immediately
02:48 940055 Deposit 3 confirmed (weaklyConfirmed)
03:08 940060 All 22,333 sat deeplyConfirmed. Channel request sent → LSP aborted: "channel funding error"
03:08-03:42 940060-62 7 total attempts, all aborted by LSP
03:44 940063 Channel opened (via Phoenix mobile app import of same seed)
03:46 940063 Splice-out from phoenixd: 19,000 sat sent to bc1q0mk5... — SUCCESS

Issue: Channel Opening Failure

Root cause: Electrum server returned very low feerate estimates:

Feerates(minimum=1 sat/byte, slow=1 sat/byte, medium=1 sat/byte, fast=2 sat/byte)

This resulted in fundingFeerate=253 sat/kw (1 sat/vB) in the OpenDualFundedChannel message. The ACINQ LSP accepted the channel parameters but aborted during interactive-tx construction with generic channel funding error.

The channel was ultimately opened by importing the seed into the Phoenix mobile app (which uses its own feerate estimation), not by phoenixd's auto channel creation. Phoenixd then synced the channel state from the peer and successfully performed a splice-out.

This is NOT a version mismatch issue — same failure occurred with both lightning-kmp:1.11.4 and 1.11.5-SNAPSHOT.

Recommendations

  1. Feerate estimation needs investigation. The Electrum blockchain.estimatefee call returns unreliable/low data from electrum.acinq.co. Consider:

    • Adding a minimum feerate floor
    • Falling back to mempool.space for fee estimation while using Electrum for address monitoring
    • Using a different Electrum server with better fee estimation

  2. Default testnet Electrum server is broken. testnet.acinq.co:51002 doesn't resolve (DNS failure). Needs to be updated to a working server like electrum.blockstream.info:60002.

  3. Channel opening fees are ~21k sat. Documentation should recommend minimum deposits of 25,000+ sat.

Final Balances

Metric Value
Deposited 22,333 sat
Channel opening fees 1,404 sat
Sent to user address 19,000 sat
Remaining in channel 1,622 sat
Splice-out tx 15539c9a61114c3bb2940dce83badaa58c540ba8064f553cf416ee1761c41969

Conclusion

The swap-in wallet infrastructure (address generation, UTXO detection, balance tracking, auto channel request) works correctly end-to-end on mainnet. The splice-out via sendtoaddress also works. The only issue is that the Electrum-based feerate estimation returns values too low for the LSP to accept, preventing autonomous channel creation. Once the channel exists (opened via Phoenix mobile in this test), all phoenixd operations work as expected.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@matthiasdebernardini